package cn.iocoder.yudao.module.system.service.user;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.system.controller.admin.user.vo.scores.UserScoresExportReqVO;
import cn.iocoder.yudao.module.system.controller.admin.user.vo.scores.UserScoresPageReqVO;
import cn.iocoder.yudao.module.system.controller.admin.user.vo.scores.UserScoresSaveReqVO;
import cn.iocoder.yudao.module.system.dal.dataobject.user.UserScoresDO;

import javax.validation.Valid;
import java.util.List;

/**
 * 用户成绩 Service 接口
 *
 * @author 芋道源码
 */
public interface UserScoresService {

    /**
     * 创建用户成绩记录
     *
     * @param userScores 成绩信息
     * @return 成绩记录ID
     */
    Long createUserScores(@Valid UserScoresDO userScores);

    /**
     * 更新用户成绩记录
     *
     * @param userScores 成绩信息
     */
    void updateUserScores(@Valid UserScoresDO userScores);

    /**
     * 删除用户成绩记录
     *
     * @param id 成绩记录ID
     */
    void deleteUserScores(Long id);

    /**
     * 获取用户成绩记录
     *
     * @param id 成绩记录ID
     * @return 成绩记录
     */
    UserScoresDO getUserScores(Long id);

    /**
     * 获取用户当前成绩记录
     *
     * @param userId 用户ID
     * @return 当前成绩记录
     */
    UserScoresDO getCurrentUserScores(Long userId);

    /**
     * 获取用户所有成绩记录
     *
     * @param userId 用户ID
     * @return 成绩记录列表
     */
    List<UserScoresDO> getUserScoresList(Long userId);

    /**
     * 批量获取用户当前成绩记录
     *
     * @param userIds 用户ID列表
     * @return 当前成绩记录列表
     */
    List<UserScoresDO> getCurrentUserScoresList(List<Long> userIds);

    /**
     * 设置用户成绩记录为当前使用
     *
     * @param userId 用户ID
     * @param scoresId 成绩记录ID
     */
    void setCurrentUserScores(Long userId, Long scoresId);

    /**
     * 根据省份和考试年份查询成绩记录
     *
     * @param province 省份
     * @param examYear 考试年份
     * @return 成绩记录列表
     */
    List<UserScoresDO> getUserScoresByProvinceAndYear(String province, Integer examYear);

    /**
     * 从system_users表迁移成绩数据到用户成绩表
     *
     * @param userId 用户ID
     * @return 是否迁移成功
     */
    boolean migrateUserScoresFromSystemUser(Long userId);

    /**
     * 更新用户当前成绩的排名信息
     *
     * @param userId 用户ID
     * @param ranking 排名
     * @param rankingRange 排名区间
     */
    void updateCurrentScoreRanking(Long userId, String ranking, String rankingRange);

    // ==================== 控制器相关方法 ====================

    /**
     * 创建用户分数
     *
     * @param createReqVO 创建信息
     * @return 分数记录ID
     */
    Long createUserScore(@Valid UserScoresSaveReqVO createReqVO);

    /**
     * 更新用户分数
     *
     * @param updateReqVO 更新信息
     */
    void updateUserScore(@Valid UserScoresSaveReqVO updateReqVO);

    /**
     * 删除用户分数
     *
     * @param id 分数记录ID
     */
    void deleteUserScore(Long id);

    /**
     * 获得用户分数
     *
     * @param id 分数记录ID
     * @return 分数记录
     */
    UserScoresDO getUserScore(Long id);

    /**
     * 获得用户分数分页
     *
     * @param pageReqVO 分页查询
     * @return 分数记录分页
     */
    PageResult<UserScoresDO> getUserScorePage(UserScoresPageReqVO pageReqVO);

    /**
     * 获得用户分数列表, 用于 Excel 导出
     *
     * @param exportReqVO 查询条件
     * @return 分数记录列表
     */
    List<UserScoresDO> getUserScoreList(UserScoresExportReqVO exportReqVO);

    /**
     * 获得指定用户的分数列表
     *
     * @param userId 用户ID
     * @return 分数记录列表
     */
    List<UserScoresDO> getUserScoresByUserId(Long userId);

    /**
     * 获得用户当前使用的分数记录
     *
     * @param userId 用户ID
     * @return 当前分数记录
     */
    UserScoresDO getCurrentUserScore(Long userId);

    /**
     * 设置用户当前使用的分数记录
     *
     * @param id 分数记录ID
     */
    void setCurrentUserScore(Long id);

    /**
     * 从用户表迁移分数数据
     */
    void migrateScoresFromUsers();

}